<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.6 sun4m) [Netscape]">
  <meta name="sandia.approval_type" content="formal">
  <meta name="sandia.approved" content="SAND2007-4748W">
  <meta name="author" content="Zoltan PI">

   <title>Zoltan User's Guide:  Migration Interface</title>

</head>
<body bgcolor="#FFFFFF">

<div align=right><b><i><a href="ug.html">&nbsp;Zoltan User's Guide</a>&nbsp;
|&nbsp; <a href="ug_interface_order.html">Next</a>&nbsp; |&nbsp; <a href="ug_interface_augment.html">Previous</a></i></b></div>

<h2>
<a NAME="Migration Functions"></a>Migration Functions</h2>
Zoltan's migration functions transfer object data to the processors in a
new decomposition.  Data to be transferred is specified through the
import/export lists returned by 
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>.
Alternatively, users may specify their own import/export lists.
<p>
The
migration functions can migrate objects based on their new part assignments
and/or their new processor assignments.  Behavior is determined by the 
<a href="ug_alg.html#MIGRATE_ONLY_PROC_CHANGES"><B>MIGRATE_ONLY_PROC_CHANGES</b></a>
parameter.
<p>
If requested, Zoltan can automatically transfer an application's data between
processors to realize a new decomposition. This functionality will be
performed as part of the call to 
<b><a href="ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
if the <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
parameter is set to TRUE (nonzero) via a call to <b><a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
This approach is effective for when the data to be moved is relatively
simple. For more complicated data movement, the application can leave <b><a href="ug_alg.html#LB Parameters">AUTO_MIGRATE</a></b>
FALSE and call <b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
itself.
In either case, <a href="ug_query_mig.html#Migration Query Functions">routines
to pack and unpack object data</a> must be provided by the application.
See the <a href="ug_examples_mig.html#Migration Example">Migration Examples</a>
for examples with and without auto-migration.
<p>The following functions are the migration interface functions. Their
detailed descriptions can be found below.
<blockquote>
<b><a href="#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>
<br><b><a href="#Zoltan_Migrate">Zoltan_Migrate</a></b>
</blockquote>

The following functions are maintained for <a href="ug_backward.html">backward compatibility</a> with previous
versions of Zoltan.  These functions are applicable
only when the number of parts to be generated is equal to the number of
processors on which the parts are computed. That is,
these functions assume "parts" and "processors" are synonymous. 
<blockquote>
<b><a href="#Zoltan_Compute_Destinations">Zoltan_Compute_Destinations</a></b>
<br><b><a href="#Zoltan_Help_Migrate">Zoltan_Help_Migrate</a></b>
</blockquote>

<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Invert_Lists"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">
int <b>Zoltan_Invert_Lists</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_to_part</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_to_part</i>);&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Invert_Lists</b>(<i>zz,&nbsp; num_known, known_global_ids,
known_local_ids, known_procs, known_to_part, num_found, found_global_ids, found_local_ids,
found_procs, found_to_part</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Invert_Lists
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_to_part, found_to_part
</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">
int <b>Zoltan::Invert_Lists</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>known_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>known_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>known_to_part</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int &<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> &<i>found_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * &<i>found_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * &<i>found_to_part</i>);&nbsp;</td>
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Invert_Lists</b> computes inverse communication
maps useful for migrating data. It can be used in two ways:
<ul>
<li> Given a list of known off-processor objects to be received by a processor,<br>
compute a list of local objects to be sent by the processor to other 
processors; or
</li>
<li> Given a list of known local objects to be sent by a processor to other processors, <br>
compute a list of off-processor objects to be received by the processor.
</li>
</ul>

For example, if each processor knows which objects it will import from other
processors, <b>Zoltan_Invert_Lists</b> computes the list of objects
each processor needs to export to other processors.  If, instead, each processor
knows which objects it will export to other processors,  
<b>Zoltan_Invert_Lists</b> computes the list of objects each processor
will import from other processors.
The computed lists are 
allocated in Zoltan; they should not be allocated by the application before
calling <b>Zoltan_Invert_Lists</b>.  These lists can be freed through a 
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the migration routine.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_known&nbsp;</i></td>

<td>The number of known objects to be received (sent) by 
this processor.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_global_ids</i></td>

<td>An array of <i>num_known</i> global IDs of known objects to be received (sent)
by this processor.
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_local_ids</i></td>

<td>An array of <i>num_known</i> local IDs of known objects to be received (sent)
by this processor.
<br>(size = <i>num_known</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_procs</i></td>

<td>An array of size <i>num_known</i> listing the processor IDs of the
processors that the known objects will be received from (sent to).
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; known_to_part</i></td>

<td>An array of size <i>num_known</i> listing the part numbers of the
parts that the known objects will be assigned to.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_found</i></td>

<td>Upon return, the number of objects that must be sent to (received from) other processors.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_global_ids</i></td>

<td>Upon return, an array of <i>num_found</i> global IDs of objects to be
sent (received) by this processor.
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_local_ids</i></td>

<td>&nbsp;Upon return, an array of <i>num_found</i> local IDs of objects
to be sent (received) by this processor.
<br>(size = <i>num_found</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_procs</i></td>

<td>Upon return, an array of size <i>num_found</i> listing the processor
IDs of processors that the found objects will be sent to (received from).</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; found_to_part</i></td>

<td>An array of size <i>num_found</i> listing the part numbers of the
parts that the found objects will be assigned to.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Invert_Lists</b>. All processors must have
the same values for these two parameters.
<p>

<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Migrate"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">
int <b>Zoltan_Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_to_part</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_to_part</i>);&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Migrate</b>(<i>zz, num_import, import_global_ids,
import_local_ids, import_procs, import_to_part,
num_export, export_global_ids, export_local_ids,
export_procs, export_to_part</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Migrate&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_to_part, export_to_part
</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C++:</td>

<td WIDTH="85%">
int <b>Zoltan::Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>import_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>import_to_part</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const int & <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> const <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>export_procs</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int * const <i>export_to_part</i>);&nbsp;</td>
</tr>
</table>

<hr WIDTH="100%"><b>Zoltan_Migrate</b> takes lists of objects to be sent
to other processors, along with the destinations of those objects, and
performs the operations necessary to send the data associated with those
objects to their destinations.  <b>Zoltan_Migrate</b> performs the following
operations using the application-registered functions:
<ul>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN">ZOLTAN_PRE_MIGRATE_PP_FN_TYPE</a></b> (if registered)
</li>
<li>
For each export object, call <b><a href="ug_query_mig.html#ZOLTAN_OBJ_SIZE_FN">ZOLTAN_OBJ_SIZE_FN_TYPE</a></b> to get object sizes.
</li>
<li>
For each export object, call
<b><a href="ug_query_mig.html#ZOLTAN_PACK_OBJ_FN">ZOLTAN_PACK_OBJ_FN_TYPE</a></b> to load communication buffers.
</li>
<li>
Communicate buffers to destination processors.
</li>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN">ZOLTAN_MID_MIGRATE_PP_FN_TYPE</a></b> (if registered).
</li>
<li>
For each imported object, call
<b><a href="ug_query_mig.html#ZOLTAN_UNPACK_OBJ_FN">ZOLTAN_UNPACK_OBJ_FN_TYPE</a></b> to move data from the buffer into the new processor's data structures.
</li>
<li>
Call <b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN">ZOLTAN_POST_MIGRATE_PP_FN_TYPE</a></b> (if registered).
</li>
</ul>
<p>
Either export lists or import lists must be specified for <b>Zoltan_Migrate</b>.
Both export lists and import lists may be specified, but both are not required.
<p>
If export lists are provided,
non-NULL values for input arguments <i>import_global_ids</i>, <i>import_local_ids</i>, <i>import_procs</i>, and <i>import_to_part</i> are optional.  
The values must be non-NULL only if no export lists are provided or if
the import lists are used by the application callback functions 
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
If all processors pass NULL arguments for the import arrays, the value of <i>num_import</i> should be -1.
<p>
Similarly, if import lists are provided, 
non-NULL values for input arguments <i>export_global_ids</i>, <i>export_local_ids</i>, <i>export_procs</i>, and <i>export_to_part</i> are optional.  
The values must be non-NULL only if no import lists are provided or if 
the export lists are used by the application callback functions 
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
If all processors pass NULL arguments for the export arrays, the value of <i>num_export</i> should be -1.
In this case, <b>Zoltan_Migrate</b> computes the export lists based on the
import lists.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; zz</i></td>

<td>Pointer to the Zoltan structure, created by <b><a href="ug_interface_init.html#Zoltan_Create">Zoltan_Create</a></b>,
to be used in this invocation of the migration routine.</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_import&nbsp;</i></td>

<td>The number of objects to be imported to parts on this processor;
these objects may be stored on other processors or may be moving to new
parts within this processor.
<br> Use <i>num_import</i>=-1 if all processors do not specify import arrays.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_global_ids</i></td>

<td>An array of <i>num_import</i> global IDs of objects 
to be imported to parts on this processor.
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>).
<br>All processors may pass <i>import_global_ids</i>=NULL if 
export lists are provided and 
<i>import_global_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b></a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_local_ids</i></td>

<td>An array of <i>num_import</i> local IDs of objects to be imported
to parts on this processor.
<br>(size = <i>num_import</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
<br>All processors may pass <i>import_local_ids</i>=NULL if 
export lists are provided and 
<i>import_local_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_procs</i></td>

<td>An array of size <i>num_import</i> listing the processor IDs of
objects to be imported to parts on this processor (i.e., the source
processors).
<br>All processors may pass <i>import_procs</i>=NULL if 
export lists are provided and 
<i>import_procs</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; import_to_part</i></td>

<td>An array of size <i>num_import</i> listing the parts to which
imported objects should be assigned.
<br>All processors may pass <i>import_to_part</i>=NULL if 
export lists are provided and 
<i>import_to_part</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; num_export</i></td>

<td>The number of objects that were stored on this processor in the previous
decomposition that are assigned to other processors or to different
parts within this processor in the new decomposition.
<br> Use <i>num_export</i>=-1 if all processors do not specify export arrays.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_global_ids</i></td>

<td>An array of <i>num_export</i> global IDs of objects to be exported
to new parts.
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>)
<br>All processors may pass <i>export_global_ids</i>=NULL if 
import lists are provided and 
<i>export_global_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_local_ids</i></td>

<td>An array of <i>num_export</i> local IDs of objects to be exported to
new parts.
<br>(size = <i>num_export</i> * <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>)
<br>All processors may pass <i>export_local_ids</i>=NULL if 
import lists are provided and 
<i>export_local_ids</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_procs</i></td>

<td>An array of size <i>num_export</i> listing the processor IDs to which
exported objects should be assigned (i.e., the destination processors).
<br>All processors may pass <i>export_procs</i>=NULL if 
import lists are provided and 
<i>export_procs</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; export_to_part</i></td>

<td>An array of size <i>num_export</i> listing the parts to which
exported objects should be assigned. 
<br>All processors may pass <i>export_to_part</i>=NULL if 
import lists are provided and 
<i>export_to_part</i> is not
needed by callback functions
<a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_PP_FN"><b>ZOLTAN_PRE_MIGRATE_PP_FN</b></
a>,
<a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_PP_FN"><b>ZOLTAN_MID_MIGRATE_PP_FN</b></
a>, and 
<a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_PP_FN"><b>ZOLTAN_POST_MIGRATE_PP_FN</b>
</a>.
</td>
</tr>
<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Migrate</b>. All processors must have the same
values for these two parameters.
<br>
 
<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Compute_Destinations"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">
int <b>Zoltan_Compute_Destinations</b>
(
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_known</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>known_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>known_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>num_found</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> *<i>found_local_ids</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int **<i>found_procs</i>);&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Compute_Destinations</b>(<i>zz,&nbsp; num_known, known_global_ids,
known_local_ids, known_procs, num_found, found_global_ids, found_local_ids,
found_procs</i>)&nbsp;
<br>INTEGER(Zoltan_INT) :: Zoltan_Compute_Destinations&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_known
<br>INTEGER(Zoltan_INT), INTENT(OUT) :: num_found
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_global_ids, found_global_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_local_ids, found_local_ids
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: known_procs, found_procs
</td>
</tr>

</table>

<hr WIDTH="100%"><b>Zoltan_Compute_Destinations</b> is a wrapper around 
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a> that excludes
part assignment arrays.  It is maintained for backward compatibility with 
previous versions of Zoltan.  
<p>
<b>Zoltan_Compute_Destinations</b> assumes the 
number of parts is equal to the number of processors.
The computed lists are 
allocated in Zoltan; they should not be allocated by the application before
calling <b>Zoltan_Compute_Destinations</b>.  These lists can be freed through a 
call to <b><a href="ug_interface_lb.html#Zoltan_LB_Free_Data">Zoltan_LB_Free_Data</a></b> or
<b><a href="ug_interface_lb.html#Zoltan_LB_Free_Part">Zoltan_LB_Free_Part</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP></td>

<td>
All arguments are analogous to those in 
<a href="#Zoltan_Invert_Lists"><b>Zoltan_Invert_Lists</b></a>. 
Part-assignment arrays <i>known_to_part</i> and <i>found_to_part</i> are
not included, as part and processor numbers are assumed to be the same in
<b>Zoltan_Compute_Destinations</b>.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<p>Note that the number of global and local ID entries (<a href="ug_param.html#NUM_GID_ENTRIES">NUM_GID_ENTRIES</a>
and <a href="ug_param.html#NUM_LID_ENTRIES">NUM_LID_ENTRIES</a>) should be
set using <a href="ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a>
before calling <b>Zoltan_Compute_Destinations</b>. All processors must have
the same values for these two parameters.
<p>

<!------------------------------------------------------------------------->
<hr WIDTH="100%">
<a NAME="Zoltan_Help_Migrate"></a>
<hr WIDTH="100%">
<table WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td VALIGN=TOP NOSAVE>C:</td>

<td WIDTH="85%">
int <b>Zoltan_Help_Migrate</b> (
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;struct <b>Zoltan_Struct</b> *<i>zz</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_import</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>import_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>import_procs</i>, 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int <i>num_export</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_global_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="ug_usage.html#Data Types for Object IDs">ZOLTAN_ID_PTR</a> <i>export_local_ids</i>,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int *<i>export_procs</i>);&nbsp;</td>
</tr>

<tr NOSAVE>
<td VALIGN=TOP WIDTH="15%" NOSAVE>FORTRAN:</td>

<td>FUNCTION <b>Zoltan_Help_Migrate</b>(<i>zz, num_import, import_global_ids,
import_local_ids, import_procs, num_export, export_global_ids, export_local_ids,
export_procs</i>)
<br>INTEGER(Zoltan_INT) :: Zoltan_Help_Migrate&nbsp;
<br>TYPE(Zoltan_Struct),INTENT(IN) :: zz&nbsp;
<br>INTEGER(Zoltan_INT), INTENT(IN) :: num_import, num_export&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_global_ids, export_global_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_local_ids, export_local_ids&nbsp;
<br>INTEGER(Zoltan_INT), POINTER, DIMENSION(:) :: import_procs, export_procs&nbsp;</td>
</tr>

</table>

<hr WIDTH="100%"><b>Zoltan_Help_Migrate</b> 
is a wrapper around <a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>
that excludes part assignment arrays.  It is maintained for backward
compatibility with previous versions of Zoltan.
<p>
<b>Zoltan_Help_Migrate</b> assumes the number of parts is equal to the
number of processors.  It uses migration pre-, mid-, and post-processing 
routines 
<b><a href="ug_query_mig.html#ZOLTAN_PRE_MIGRATE_FN">ZOLTAN_PRE_MIGRATE_FN_TYPE</a></b>,
<b><a href="ug_query_mig.html#ZOLTAN_MID_MIGRATE_FN">ZOLTAN_MID_MIGRATE_FN_TYPE</a></b>, and 
<b><a href="ug_query_mig.html#ZOLTAN_POST_MIGRATE_FN">ZOLTAN_POST_MIGRATE_FN_TYPE</a></b>, respectively, which also exclude part assignment arrays.
<br>&nbsp;
<table WIDTH="100%" >
<tr>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP></td>

<td>
All arguments are analogous to those in 
<a href="#Zoltan_Migrate"><b>Zoltan_Migrate</b></a>. 
Part-assignment arrays <i>import_to_part</i> and <i>export_to_part</i> are
not included, as part and processor numbers are assumed to be the same in
<b>Zoltan_Help_Migrate</b>.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp;&nbsp; int</td>

<td><a href="ug_interface.html#Error Codes">Error code</a>.</td>
</tr>
</table>

<br>
<!------------------------------------------------------------------------->
<hr WIDTH="100%">[<a href="ug.html">Table of Contents</a>&nbsp; | <a href="ug_interface_order.html">Next:&nbsp;
Ordering Interface</a>&nbsp; |&nbsp; <a href="ug_interface_augment.html">Previous:&nbsp;
Functions for Augmenting a Decomposition</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
